#%RAML 0.8
title: Login
version: v1
baseUri: http://github.com/org/folio/mod-auth/login_module

documentation:
  - title: mod-auth login API
    content: This module provides a username/password based login mechanism for folio credentials

schemas:
  - credentials: !include schemas/credentials.json
  - credentialsListObject: !include schemas/credentialsListObject.json
  - loginCredentials: !include schemas/loginCredentials.json
  - errors: !include ../../raml-util/schemas/errors.schema
  - error: !include ../../raml-util/schemas/error.schema
  - parameters: !include ../../raml-util/schemas/parameters.schema

traits:
  - validate: !include ../../raml-util/traits/validation.raml
  - pageable:
      queryParameters:
        length:
          description: "The maximum number of results to return."
          required: false
          type: integer
          example: 10
          minimum: 1
          default: 10
          maximum: 1000
        start:
          description: "The starting index in a list of results (starts at one)."
          required: false
          type: integer
          minimum: 1
          default: 1
          maximum: 1000
  - sortable:
      queryParameters:
        sortBy:
          description: "A comma-separated list of fieldnames to sort by"
          required: false
          type: string
  - queryable:
      queryParameters:
        query:
          description: "A query string to filter users based on matching criteria in fields."
          required: false
          type: string


/authn:
  /login:
    post:
      description: Get a new login token
      body:
        application/json:
          schema: loginCredentials
      responses:
        201:
          headers:
            x-okapi-token:
          body:
            application/json:
              schema: loginCredentials
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /credentials:
    get:
      description: Get a list of user credentials
      is: [
        pageable,
        sortable,
        queryable
      ]
      responses:
        200:
          body:
            application/json:
              schema: credentialsListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new login to the system
      is: [validate]
      body:
        application/json:
          schema: loginCredentials
      responses:
        201:
          body:
            application/json:
              schema: loginCredentials
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{username}:
      get:
        description: Get login credentials for a single user
        responses:
          200:
            body:
              application/json:
                schema: credentials
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify a user's login credentials
        body:
          application/json:
            schema: loginCredentials
        responses:
          200:
            body:
              application/json:
                schema: loginCredentials
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a user's login credentials from the system
        responses:
          204:
            body:
              text/plain: !!null
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description:
              "Internal server error"
            body:
              text/plain:
                example: "Internal server error"


